<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//Tigris//DTD XHTML 1.0 Transitional//EN"
"http://style.tigris.org/tigris_transitional.dtd">
<html>
<head>
 <style type="text/css">
/* <![CDATA[ */ 
@import "css/readyset.css"; 
@import "css/inst.css";
/*  ]]> */
 </style>

<link rel="stylesheet" type="text/css" href="css/print.css" media="print" />
 <title>Source Code Organization and Build System</title>
</head>

<body>
<div class="app">
<div class="readyset">
 <h2><a href="design.html">Design</a> &gt; Source Code Organization and Build System</h2>

 <div id="releaseinfo">
 <h3>Release Information</h3>
 <table border="1" cellpadding="3" cellspacing="2" class="axial">
  <tr>
   <th>Project:</th> 
   <td><a href="index.html">PROJECTNAME</a></td> 
  </tr>
  <tr>
   <th>Internal Release Number:</th> 
   <td>X.Y.Z</td> 
  </tr>
  <tr>
   <th>Related Documents:</th> 
   <td>
    <div><a href="http://jakarta.apache.org/tomcat/tomcat-4.1-doc/appdev/build.xml.txt">Example build.xml for Tomcat</a></div>
    <div><a href="http://ant.apache.org/manual/index.html">Apache Ant manual</a></div>
    <div>LINKS TO RELEVANT STANDARDS</div>
    <div>LINKS TO OTHER DOCUMENTS</div>
   </td>
  </tr>
 </table>
 </div> <!-- /releaseinfo -->



 <div id="overview">
 <h3>Overview</h3>

 <div class="todo">
  TODO: Answer the questions below to help you define your source code
  organization and build process.  Some example text is provided.  Add
  or delete text as needed.  E.g., not all projects try to be platform
  independent.
 </div>

 <dl>
  <dt>What are the most important facts that a developer should know
  about this source code organization and build system?</dt>

  <dd class="sample1">It roughly follows the standard proposed in the Tomcat documentation and
  is very similar to the organization used on many open source
  projects at the Apache Software Foundation.</dd>


  <dt>What are the ranked goals of this source code organization and build system?</dt>

  <dd class="sample1">
   <ol>
    <li>Separation of files by type</li>

    <li>Separation of version-controlled files from files generated by
    the build process</li>

    <li>Compatibility with standard build processes</li>

    <li>Platform independence</li>
   </ol>
  </dd>

 </dl>
 </div> <!-- /overview -->



 <div id="directories">
 <h3>Key Directories and Files in Developer Working Copies</h3>

 <div class="todo">
  TODO: Describe the purpose of each directory that will appear in a
  developer's work copy, also include any files that are important to
  the overall structure or build process.
 </div>


 <table border="1" cellpadding="3" cellspacing="2" width="100%">
  <tr><th>Path</th><th>VC</th><th>Description</th></tr>
  <tr>
   <td>build.xml</td>
   <td>Yes</td>
   <td>Build file</td>
  </tr>
  <tr>
   <td>build.properties</td>
   <td>Yes</td>
   <td>Build properties file</td>
  </tr>
  <tr>
   <td>src/</td>
   <td>Yes</td>
   <td>Source code</td>
  </tr>
  <tr>
   <td>src/java/</td>
   <td>Yes</td>
   <td>Java source code</td>
  </tr>
  <tr>
   <td>src/java/[Nested packages]/</td>
   <td>Yes</td>
   <td>Java source code of classes in each package</td>
  </tr>
  <tr>
   <td>src/java/[Nested packages]/test/</td>
   <td>Yes</td>
   <td>Java source code of unit tests for classes in each package</td>
  </tr>
  <tr>
   <td>web/</td>
   <td>Yes</td>
   <td>HTML and JSP files</td>
  </tr>
  <tr>
   <td>web/css/</td>
   <td>Yes</td>
   <td>CSS files, if any</td>
  </tr>
  <tr>
   <td>web/images/</td>
   <td>Yes</td>
   <td>Image files, if any</td>
  </tr>
  <tr>
   <td>web/WEB-INF/web.xml</td>
   <td>Yes</td>
   <td>Java web application configuration file</td>
  </tr>
  <tr>
   <td>conf/</td>
   <td>Yes</td>
   <td>Configuration files, if any</td>
  </tr>
  <tr>
   <td>data/</td>
   <td>Yes</td>
   <td>Initial data to load into database and/or file system, if any</td>
  </tr>
  <tr>
   <td>lib/</td>
   <td>Yes</td>
   <td>Libraries reused by this project, if any</td>
  </tr>
  <tr>
   <td>scripts/</td>
   <td>Yes</td>
   <td>Command-line utility scripts used by this project, if any</td>
  </tr>
  <tr>
   <td>www/</td>
   <td>Yes</td>
   <td>Project documents (e.g., overview, plan, requirements, and design)</td>
  </tr>
  <tr>
   <td>build/</td>
   <td>No</td>
   <td>Output of build process</td>
  </tr>
  <tr>
   <td>build/WEB-INF/classes/</td>
   <td>No</td>
   <td>Compiled code output by build process</td>
  </tr>
  <tr>
   <td>dist/docs/api/</td>
   <td>No</td>
   <td>API documentation output from build process</td>
  </tr>
  <tr>
   <td>dist/PROJECTNAME-VERSION.war</td>
   <td>No</td>
   <td>Deployable web archive of classes and config files generated by build process</td>
  </tr>
 </table>
 </div> <!-- /directories -->



 <div id="targets">
 <h3>Build Targets</h3>

 <div class="todo">
  TODO: Describe the build targets that developers will use in daily
  development.  The examples below should fit most projects.
 </div>


 <table border="1" cellpadding="3" cellspacing="2" width="100%">
  <tr><th>Target</th><th>Description</th></tr>
  <tr>
   <td nowrap="nowrap">compile = default</td>
   <td>Compiles Java source code and creates .class
       files under the "build" directory.</td>
  </tr>

  <tr>
   <td>dist</td>
   <td>Packages the system for distribution/deployment to servers
       or end users.  Specifically, it creates .war archive of compiled
       classes and configuration files.</td>
  </tr>

  <tr>
   <td>install</td>
   <td>Places executable code into location where it will actually be
       executed.  Specifically, it copies .war file into Tomcat's
       webapps directory for use.  You must then restart Tomcat or use
       the "reload" link in the Tomcat Manager.</td>
  </tr>

  <tr>
   <td>javadoc</td>
   <td>Generates Java API documentation under "build/docs/api/".</td>
  </tr>

  <tr>
   <td>clean</td>
   <td>Deletes files generated by previous build commands.
       Files under version control are not touched.</td>
  </tr>
 </table>
 </div> <!-- /targets -->



 <div id="options">
 <h3>Build Configuration Options</h3>

 <table border="1" cellpadding="3" cellspacing="2" width="100%">
  <tr><th>Property</th><th>Description</th></tr>

  <tr>
   <td>app.name</td>

   <td>The name of this application. This should be one short word.  Used
       in the name of resulting package files.  Specifically, the .war
       file.  And, it will be used to access the application via
       http://localhost:8080/APP.NAME/</td>
  </tr>

  <tr>
   <td>app.version</td>
   <td>Version number of this release.  Used in the name of
       resulting package files.  Specifically, the .war file.</td>
  </tr>

  <tr>
   <td>webapps.path</td>
   <td>Path to the Tomcat "webapps" directory.  Defaults
       to <tt>C:\Program Files\Apache Group\Tomcat 4.1\webapps\</tt></td>
  </tr>

 </table>

 <p>These build system properties can be modified by editing the
 build.properties file.</p>
 </div> <!-- /options -->



 <div id="checklist">
 <h3>Source Code Organization and Build System Checklist</h3>

 <dl>
  <dt>Separation of files by type: Are files separated by type?</dt>

  <dd class="sample1">Yes.  Except that application JSP and HTML files are in the same
  directory, which is convenient because sometimes we change an HTML
  file to be a JSP file.</dd>


  <dt>Separation of version-controlled and non-version controlled
  files: To what extent has this been achieved?</dt>

  <dd class="sample1">It has been achieved.  Everything is under version control
  except for the "build" directory. No step in the build process
  should create or modify any file in any other directory.</dd>


  <dt>Compatibility with standard build processes: To what extent has
  this been achieved?</dt>

  <dd class="sample1">So far, so good.  We can use build.xml files that are very close
  to the examples that come with Ant.  One difference is that we keep
  our technical documentation under "www" rather than under
  "docs".  Also, we have avoided the use of custom ant tasks.</dd>

  <dt>Platform independence: To what extent has
  this been achieved?</dt>

  <dd class="sample1">We are using Ant, which is itself platform independent.  The
  names of the files and directories should work across platforms
  because they do not rely on case-sensitive names.  We assume that
  the utility scripts in the "scripts" directory support all needed
  platforms and we have not created directories for different versions
  of these files aimed at specific platforms.</dd>



  <dt>Have these implementation decisions been communicated to the
  development team and other stakeholders?</dt>

  <dd class="sample1">Yes, everyone understands.  Feedback is
  welcome.</dd>

  <dd class="sample1">No, this is a risk that is noted in the <a
  href="plan.html#risks">Risk Management</a> section.</dd>

 </dl>
 </div> <!-- /checklist -->

</div>


 <p class="todo">
  TODO:  Check for <a
  href="http://readyset.tigris.org/words-of-wisdom/design-src-org.html">words
  of wisdom</a> and discuss ways to improve this template.
  Or, evaluate the ReadySET Pro <a title="pro use case template and sample test plan"
  href="http://www.readysetpro.com/">professional source code organization template</a>.
 </p>

<div class="legal1">Company Proprietary</div>

<div class="footnote">
 Copyright &#169; 2003-2004 Jason Robbins.  All rights reserved. <a href="readyset-license.html">License terms</a>.
 Retain this copyright statement whenever this file is used as a
 template.
</div>

</div>
</body>
</html>
